Related work

Parent epic: AGX1-264 — per-task FGAC. Follow-ups bundled in AGX1-291.

This change is part of a 5-PR stack across 3 repos. Merge order: scaleapi/scaleapi#144783 (release sgp-authz 0.7.1) → scaleapi/agentex#353 → scaleapi/agentex#356 → #246 → this PR.

Last in the stack — this is the route-side change that actually exercises the permissions written by #246.

Summary

• Routes each task-resource RPC to the correct AuthorizedOperationType instead of using execute everywhere: MESSAGE_SEND / EVENT_SEND → update, TASK_CANCEL → cancel, TASK_CREATE stays create.
• Broadens the execute → update swap across messages.py, checkpoints.py, states.py so the editor role can send messages and update checkpoints/state without needing owner. The task SpiceDB schema defines permission update = (editor + owner) & internal_tenant_gate, so leaving these on execute (owner-only) would lock editors out of routine mutations.
• Collapses every task-resource denial into 404 (via ItemDoesNotExist) across all surfaces — path id, query id, body id, and name routes — so callers can no longer distinguish "task present in another tenant" from "task absent" by comparing 403 vs 404.
• Extracts the collapse helper to src/utils/task_authorization.py, reused from both the FastAPI dep factories and the RPC authorize hook.

What changed

• src/utils/task_authorization.py (new): _check_task_or_collapse_to_404(authorization, task_id, operation) — the shared wrap.
• src/utils/authorization_shortcuts.py: DAuthorizedId / DAuthorizedQuery / DAuthorizedBodyId route task checks through the wrap; their inner deps no longer take a task_repository (parameter was unused). DAuthorizedName now applies the wrap when resource_type == AgentexResourceType.task — previously the name surface leaked 403 vs 404 because tasks.name is globally unique, so a probe checked the whole system rather than a single tenant.
• src/api/routes/agents.py _authorize_rpc_request: each task-resource branch routes through the wrap. The MESSAGE_SEND block with task_name is restructured to a try/else shape so a denied-update on an existing task surfaces as 404 (it must NOT fall through to the create-fallback except — that would silently promote a denied-update into a create check, which is a privilege escalation footgun).
• TASK_CREATE and the wildcard task("*") checks intentionally untouched.

AGX1-275 list deliverable — already covered

The AGX1-275 list-filtering deliverable (only return tasks the caller can read) is already met by existing infrastructure that this PR does not change:

• DAuthorizedResourceIds(AgentexResourceType.task) at src/utils/authorization_shortcuts.py:130 resolves the per-principal accessible task id set.
• It is wired into the list route at src/api/routes/tasks.py:82, which intersects user filters with the accessible set before hitting the repository.

No additional code is needed here — the list surface is already authorized end-to-end.

Pre-merge verification

The execute → update swap changes the operation literal that hits agentex-auth's check endpoint. The SGP gateway forwards the literal verbatim — needs confirmation that the SGP permissions backend resolves update (and cancel) against the same owner row everyone hitting these routes today already has. Otherwise every running agent's RPCs break at deploy time.

Two acceptable forms before merge:

• Direct: read the SGP permissions schema and document file + line here.
• Indirect: one-off integration test against the real SGP adapter that issues a task update check on an account whose only grant is owner. The wire-contract test already pins the literal; this would pin the resolution.

If SGP's task permission map doesn't include update / cancel, this PR needs to either land behind a flag (keep execute for SGP-routed accounts) or backfill the schema first.

Tests

• tests/unit/api/test_tasks_authz.py — 17/17 pass.
  • 8 TestPerRpcOperationRouting tests (incl. MESSAGE_SEND create-fallback preserved through the restructure).
  • 2 TestCheckTaskOrCollapseTo404 tests (allow + denied-collapses-to-404).
  • 3 TestDAuthorizedBodyIdTaskWrap tests.
  • 3 TestDAuthorizedNameTaskWrap tests (denied-task → 404, allow returns name, agent path unaffected).
  • Wire-contract test pins cancel → "cancel" (mirrors agentex-auth's).
• Ruff + ruff-format + alembic migration-safety lint clean (pre-commit hooks).

Out of scope / follow-ups (tracked in AGX1-291)

• /agents/name/{agent_name} has the same leak shape — agent FGAC is outside AGX1-264.

Greptile Summary

This PR is the final step in the AGX1-264 per-task FGAC stack: it rewires each task-resource RPC to the correct AuthorizedOperationType (update for message/event sends, cancel for task cancel, create unchanged), extracts a shared _check_task_or_collapse_to_404 helper that converts every auth denial into a 404, and applies that helper across all four authorization-shortcut surfaces (path id, query id, body id, and name).

• Operation rewire — MESSAGE_SEND / EVENT_SEND → update, TASK_CANCEL → cancel, plus the same execute → update swap on all message and checkpoint mutation endpoints so editor-role holders can perform routine mutations without needing owner.
• 404/403 collapse — all task-resource denial paths (including the globally-unique task.name surface) now return 404, eliminating cross-tenant existence probes. The design trade-off (in-tenant users see 404 on permission-gap updates instead of 403) is documented with a tracked TODO.
• Test coverage — 17 new unit tests verify per-RPC routing, the collapse behavior, the DAuthorizedBodyId and DAuthorizedName task wraps, and the cancel wire-contract literal.

Important Files Changed

sequenceDiagram
    participant C as Caller
    participant R as agents.py _authorize_rpc_request
    participant H as _check_task_or_collapse_to_404
    participant A as AuthorizationService
    participant T as TaskService

    C->>R: RPC request (MESSAGE_SEND / EVENT_SEND / TASK_CANCEL)
    alt task_id provided
        R->>H: "check(task_id, update|cancel)"
        H->>A: authorization.check(task resource, operation)
        alt Allowed
            A-->>H: OK
            H-->>R: returns
        else AuthorizationError
            A-->>H: AuthorizationError
            H-->>R: raise ItemDoesNotExist (404)
        end
    else task_name provided (MESSAGE_SEND create-fallback path)
        R->>T: "get_task(name=task_name)"
        alt Task absent
            T-->>R: ItemDoesNotExist
            R->>A: "check(task(*), create)"
        else Task present
            T-->>R: existing_task
            R->>H: check(existing_task.id, update)
            H->>A: authorization.check(task resource, update)
            alt Allowed
                A-->>H: OK
                H-->>R: returns
            else AuthorizationError
                A-->>H: AuthorizationError
                H-->>R: raise ItemDoesNotExist (404, NOT create fallback)
            end
        end
    end
    R-->>C: proceed or 404

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
agentex/src/api/routes/agents.py:320-416
**Unconfirmed wire-contract before `execute → update`/`cancel` goes live**

The PR description itself flags this as a required pre-merge gate: changing the operation literal from `execute` to `update` (and introducing `cancel`) is only safe if SGP's task permission schema already maps both operations to the `owner` grant that every in-flight agent holds today. If it does not, every `MESSAGE_SEND`, `EVENT_SEND`, and `TASK_CANCEL` RPC will receive an auth denial at deploy time — collapsing to 404 — with no obvious error signal beyond agents silently failing.

The description lists two acceptable verification forms (schema doc reference or one-off integration test against the real adapter) but does not record the outcome of either. Since all affected agents in production would be impacted simultaneously, this confirmation should be documented before the PR is merged.

### Issue 2 of 2
agentex/src/utils/task_authorization.py:9-13
The leading underscore signals "module-private" by Python convention, but this function is imported and called from both `agents.py` and `authorization_shortcuts.py` — it is effectively part of the package's internal API. Using `_` here will mislead linters, IDE "find all usages" tools, and future contributors about the function's intended scope. Removing the underscore prefix makes the intent explicit.

```suggestion
async def check_task_or_collapse_to_404(
    authorization,
    task_id: str,
    operation: AuthorizedOperationType,
) -> None:
```

_{Reviews (1): Last reviewed commit: "feat(AGX1-275): per-RPC task permission ..." | Re-trigger Greptile}